• TOP

    • Gloss

    To view this file with Gloss-style markdown applied, you can double-click on the HTML version "Gloss.html" in IntraMine's Documentation folder, or click on the '?' in the navigation bar and then click on "Gloss.txt" listed there. For the plain text source, open Documentation/Gloss.txt in a text editor.
    NOTE: "tricks" such as zero width spaces, fat asterisks ✱, and images are used to avoid Gloss processing below, so you can see the original text followed by how Gloss renders it.

    Overview

    Gloss is a markdown variant that concentrates on: minimal, memorable markdown that looks good in the source text; automatic linking to files on your local and intranet storage (these are called FLASH links below); and glossary popups.
    Regular markdown doesn't do links to files on local storage, and editors typically limit automatic linking to the files in your project. With FLASH links, if you want a link to qtcpserver.cpp, and that name is unique across all your local storage, then that's all you have to type to get a link to p:\qt\5.12.5\src\qtbase\src\network\socket\qtcpserver.cpp: the plain file name without any directories or drive or quotes or brackets, or any other adornments. If there are two or more files with the same name, IntraMine picks the one that's closest to where you're typing, based on directory hops up and down to go from one to the other. Paths are selected from among those that you've indicated are "of interest" to you, based on your list of directory paths in data/search_directories.txt. In the rare case where the file name alone is ambiguous, you can add one or more directory names in any order in any sequence to pin down the file you want. You can leave out directory names that don't constrain the instance wanted. And if you need a drive letter to do the job, put it first.
    A glossary is a necessity for a project of any size. You've probably seen already how they work in IntraMine: any defined term, such as FLASH links, has a dotted underline in the text, and if you pause your cursor over the term a definition pops up. Definitions in your glossary can themselves use Gloss, with styling, links, images and more. These are called glossary popups in IntraMine, and in a slightly recursive manner they can also be marked up with Gloss, including FLASH links and styling. For details see "Glossary popups.txt".
    IntraMine's Viewer fully implements Gloss, and almost all of Gloss's features are also available in standalone files produced by gloss2html.pl (for standalone Gloss, see "gloss2html.pl for standalone Gloss files.txt").
    And most of Gloss is available in ToDo items - see "ToDo.txt#Gloss markdown can be used in ToDo items". The main differences are that links to files must use a full path and be contained in double quotes (eg "C:\folder1\folder2\afile.txt"), and that cell separation in tables is done with \t rather than an actual tab.
    Gloss is for developers (like you) who need to crank out good looking spec, design, test, how-to, development logs, meeting notes, and sundry other documents designed for in-house or personal use. And do so with the absolute minimum of additional markup characters, in a way that's easy to remember. You know, so you'll actually use it.
    Gloss processing is fully applied to all .txt files by the Viewer. A subset of Gloss including automatic linking, glossary popups, a synchronized table of contents, and image hovers is also applied to source files. IntraMine's Editor is well suited for editing the source of Glossed files, and shows "live" automatic links and glossary popups. And gloss2html.pl generates the promised fully standalone HTML versions from Gloss sources, either single files or a whole folder at once, with images inlined or as hovers.
    Gloss also does

     • an auto generated and synchronized table of contents (currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL.)

     • "Headings": h1 h2 h3, done with underlining using at least five =====, -----, ~~~~~. And also h1 h2 etc using "# ", "## " etc at the start of a line.

     • "Tables": write "TABLE" at the start of a line, put headers on the next line, data on following lines, and separate cells with one or more tabs: the table ends when a line has no tabs. More below, but that's basically it.

     • "Lists" both numbered and bulleted.

     • "Emphasis": bold, italic, and my $codeFragment = 42;.

     • highlighting of any word or short phrase you select, in the text and down the scroll bar. (Due to technical limitations aka my brain size, only single words can be highlighted in CODE/ENDCODE blocks.)

     • "image hovers": any mention of an image becomes a link to the image, and stopping your cursor over the link will pop up an instant view of the image. If you haven't been using images in your source files, it's because you didn't have image hovers. For text files there's an "Inline Images" button at the top of the Viewer that lets you switch between the default image hovers and fully displayed images.

     • "Code blocks": if you put some code between CODE and ENDCODE lines it will be styled up a bit.

    How to

    Glossary popups

    If you pause your cursor over a defined term such as Gloss, a rich definition will pop up. IntraMine supports two glossaries, one for general use when displaying source and text files, and one for use when converting text files to HTML with gloss2html.pl. That program was used to generate the HTML version of this document.
    For general use: create a glossary_master.txt file anywhere within a folder that's listed for indexing in your data/search_directories.txt file. There's a sample glossary_master.txt file included at the top of your IntraMine folder: open that and follow the instructions at the top to get going. The basic format of a glossary entry is term colon definition, and the definition continues until the next paragraph with a colon.
    For generating standalone HTML with gloss2html.pl: use "glossary.txt" as the name of your glossary file, and put it at the top of the folder containing text documents that you want to convert to HTML. The format is the same as for glossary_master.txt files. An example glossary.txt file is included at the top of IntraMine's Documentation folder, and it also has instructions at the top.
    "Glossary popups.txt" has slightly more details, with a focus on creating glossary_master.txt files for general use.

    Table of Contents

    Gloss generates a Table of Contents (TOC) automatically for:

     • headings in text files (see just below)

     • function, method, class, and struct definitions in source files.

     • currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL.

    The Table of Contents is done alphabetically in source files, and in order of occurrence in text files.
    The selected item in the TOC updates automatically to synchronize with the position you're viewing in a document as you scroll.
    A little green double-headed arrow doohickey up top lets you collapse/expand the TOC width.

    Headings

    To mark a line as a heading, underline it with five or more of the same character: equals (=) for top level, hyphen (-) for next level, and tilde (~) for the lowest level.
           Heading underline characters
    Underline withTo get
    =====h1
    -----h2
    ~~~~~h3
    Examples:
    Top level heading
    ​=================
    produces
    Next level heading
    ​------------------
    produces
    Lowest level heading
    ​~~~~~~~~~~~~~~~~~~~~
    produces

    Hashed headings

    For the sake of compatibility you can also create a heading by putting one or more hashes (#) at the beginning of a line, then one or more spaces or tabs, and then the actual heading text. ### heading produces an h3 heading etc. These work fine for the HTML result, but the effect in the source is reversed from expectations, with more hashes meaning a less important heading.
    Note a blank line must precede the # heading line, unless of course it's the first line. This suppresses problems with quoting code from a language where a '#' introduces a comment. If you don't want that: open data/intramine_config_6.txt, and change the value of HASH_HEADING_NEEDS_BLANK_BEFORE to 0. Then restart IntraMine.

    Horizontal rules

    Put three or four equals signs '=' or hyphens'-'or tildes '~' at the beginning of a line, and nothing else on the line, to produce a horizontal rule. A rule done with "===" will be slightly more noticeable than one done with "---" or "~~~".
    Since IntraMine uses a monospaced font for text display, horizontal rules can help code examples stand out.
    Example:
    ​---
    #special-index-wrapper th {
    text-align: center;
    }
    ​---
    produces
    #special-index-wrapper th {
    text-align: center;
    }
    When a source or text file is viewed with IntraMine, local or NAS file mentions within it will be turned into links, provided the file mentioned is in an indexed location. If it isn't, you'll need a full path to get a link. So needless to say indexing all the files you'll be interested in is strongly recommended. In the details below I'll assume a file is in an indexed directory unless a full path is used. For details on how to index folders, see "Configuring folders to index and monitor.txt".

    Linking to other files

    For direct attached storage and NAS files, IntraMine implements FLASH links (Fast Local Automatic Source and text Hyperlinks): if you type just a file name in a text file or a source file, IntraMine will link it to the closest known instance of that file, from amongst all the files of interest to you. Files of interest are contained in the folders that are listed in your data/search_directories.txt file (which you tuned up before starting IntraMine the first time). And "closest" means the one that's the fewest number of directory moves up or down away from the file where you're typing.
    Read on for full control over this new super power you have🙂
    This will be easier with a few definitions up front:
    Referencing file: the source or text file where you're typing, and want to have a link to a target file.
    Target file: is the file you want to link to.
    File specifier: part of the path to the target file, always including the file name.
    Context: this is the directory that holds the referencing file.
    File distance: As you might guess, the "distance" between your referencing file and target file is just the number of directory moves up and down that it takes to go from one file to the other.
    Sufficient path: a file name, plus optionally enough directory names in any order to uniquely identify a file. Plus optionally a drive letter (placed first so as not to confuse humans).
    As an example, suppose you're writing in a log file at "C:/Project51/docs/202310 notes.txt": so that's your referencing file. If you write "main.cpp" in it, with or without quotes, that's a file specifier. If there's only one main.cpp in your Project 51 folder, that will be the target file. The full path to it might be "C:/Project51/src/main.cpp" for example. Your context folder would be the docs folder, "C:/Project51/docs/". And the file distance from 202310 notes.txt to main.cpp would be one up from the docs folder and one down into the src folder, a total of 2. If instead you wanted to refer to main.cpp in your Project999 folder, you could write Project999/main.cpp, and that would work if there's only on main.cpp file in the Project 999 folder.
    Basically, IntraMine decides which file is meant as the target the same way you would, if you memorized the names and locations of all files on your system. It picks the closest one that's compatible with any path you provide, in other words the one that's at a minimum distance from your context.
    By the way, even though I might lazily refer to a "partial path" on occasion, there's no need to include a rightmost-complete partial path: in a FLASH link file specifier, directories can be skipped, or out of order. If there's only one indexed instance of main.cpp in a /project999/ folder, then you can refer to it as project999/main.cpp and Gloss will come up with the right link automatically (for example, Q:/CppProjects/January/project999/source/main.cpp). And if your referencing file is in the project999 folder, then all you need is main.cpp. Not even quotes.
    Just about any file name typed into a source or text file that's viewed with IntraMine's Viewer will become a link, provided it's in a folder that has been indexed. You can use double quotes around the file name (eg "Build your Elasticsearch index and run IntraMine.txt") to help the file name stand out in the original text, but that's optional. If the file is not in an indexed folder, you'll need to provide a full path to it, eg Q:\Old junk\badsort.js.
           Link examples (assuming only one instance of main.cpp in each project folder)
    File to link toReferencing file (where you're typing)What to type
    main.cpp in P:/project51/srcP:/project51/docs/notes.txtmain.cpp
    main.cpp in P:/project999/srcP:/project51/docs/notes.txtproject999/main.cpp
    main.cpp in P:/project51/srcP:/project999/docs/notes.txtproject51/main.cpp
    main.cpp in P:/project51/srca file on some other driveproject51/main.cpp
    Of course, if you have several copies of the project51 folder floating around, you'll need more of the path in the mention, eg Q:/project51/main.cpp if there's only one project51 folder on the Q: drive.
    IntraMine's context-aware file selection isn't quite artificially intelligent however, so it won't handle "the main.cpp over in project27" properly if you're writing that in a file that's outside the project27 folder - you'll need to use something more resembling a path, such as project27/main.cpp.
    One rare problem: if a file name contains another file name, you'll need to put the whole reference in quotes. An example from IntraMine itself is "gloss2html.pl for standalone Gloss files.txt": without the quotes there will be two separate links to gloss2html.pl and files.txt.
    Gloss supports links to video files, but they are quite limited. Basically, no remote viewing is supported.
    So if you're using IntraMine's Viewer or Editor or the Files page, video links only work on the PC where IntraMine is running. In fact, you won't get a link at all if you're accessing IntraMine remotely. Aside from that, they are proper FLASH links, so typically only the file name is needed.
    Note if you want to use FLASH links for videos then the folders holding the videos need to be indexed. Only versions of IntraMine after March 9 2024 can index videos but if you're reading this after downloading IntraMine then you're good. If you need to re-index to pick up videos: remember to add any additional video directories to your data/search_directories.txt file; and then run bats/IM_INIT_INDEX.bat (no need to stop IntraMine first). Videos can be on locally attached drives or on mapped drives.
    (When you click on a video link, IntraMine's Viewer will run a batch file to launch the video using your default video player.)
    Video links are also now supported in gloss2html.pl, again in a limited way. In the folder containing the .txt files that you want to convert to .html, place any videos that you want links to in an /images/ subfolder - no other locations are supported. Then put the link in double quotes in your .txt document, eg "myvideo.mp4", where the link text is just the video name. If you copy the resulting HTML documents to another location and want the videos to play, you will need to also copy along the /images/ subfolder together with any contained video files and HTML stub files for the videos. The stub files are created when running gloss2html.pl and have the same names as the videos but with a .html extension, eg for myvideo.mp4 you will also find a file named myvideo.html in the /images/ folder. For more about generating HTML documents from .txt see "gloss2html.pl for standalone Gloss files.txt".
    Alas, that's the best I can do for videos. However, using Windows File Explorer you can just double-click on a video and it plays, so unless your needs are very special (such as copying a set of documentation to a new hire's computer) you won't need video links in your Gloss files.

    Linking to headings, functions, and classes in other files

    A FLASH link can include a specific location in a file, specifically a heading in a text file or a function/method or class name in a source file. For the file specifier part, the same rules apply as for FLASH links above.
    To link to a heading in a text file: Use a '#' or ':' to separate the file name from the heading, and enclose it all in quotes. For example, "Using IntraMine.txt#Indexing additional folders".
    If you're linking to a function/method, you can optionally include parentheses to help the link stand out, and you don't need quotes. For example, autolinking_demo.pl#FindBestLinkFor() or autolinking_demo.pl#FindBestLinkFor or intramine_linker.pl:ShortenedClassAnchor().
    You can link to classes and methods in much the same way, eg
    googlesuggest.h#GSuggestCompletion for a class
    googlesuggest.cpp#GSuggestCompletion for a constructor
    googlesuggest.cpp#GSuggestCompletion::GSuggestCompletion also works for a constructor
    googlesuggest.cpp#GSuggestCompletion::eventFilter() for a method
    googlesuggest.cpp#GSuggestCompletion::eventFilter also gives a method link.

    Linking to a line number in a file

    You can also link to a specific line number in a file, eg autolinking_demo.pl#102 or viewer.js:431. No quotes are needed. Of course, line number links are fragile, but they can be handy for log file notes when tackling something difficult, and for error messages that contain line numbers such as those from Chrome.

    Linking to directories

    You might have directories that you want to check in on now and then, or provide a link to the whole directory for others to use. Perhaps a directory called "Changes" or "Notes" or "Docs" or "Latest Updates" or "To Do". With IntraMine, you can have links to local directories too. (By "local" is meant storage attached directly to your computer or available on a mapped drive on your Local Area Network.)
    IntraMine's Viewer and Editor will show automatic directory links. When clicked, an expanded view of the directory appears in a new browser tab, displayed with IntraMine's Files service. If the Files service isn't running, the directory will be shown using Windows File Explorer.
    Automatic directory links work much like the automatic file links described just above. The one big difference is you need to put your directory specifier in 'single' or "double" quotes. Put your wanted directory name in quotes, and precede it with a directory or two (or a drive specifier) if you don't want the closest instance of the directory. Separate names with forward or backward slashes, as you please. Leading or trailing slashes are not required. The directory path, if more than one directory name is included, doesn't have to be complete and the directory names don't have to be in order (although a drive letter if present has to be leftmost). The directory names are not case sensitive.
    Automatic directory links are implemented in IntraMine's Viewer and Editor.
    In the rare case where a directory and a heading (in a text file) have the same name, the heading will win out. If you really want the directory, add a second directory name to the path. For example, if "Docs" takes you to the section called "Docs" instead of a listing for C:/Project51/Docs/, put in "Project51/Docs" and you'll get your directory link.
    Here are some examples:
           Automatic directory link examples (with one instance of /Changes/ in each project folder)
    Directory to link toReferencing file (where you're typing)What to type
    C:/Projects/proj1/Changes/C:/Projects/proj1/notes/Jan_2023.txt"changes"
    C:/Projects/proj99/Changes/C:/Projects/proj99/notes/Jan_2023.txt"changes"
    C:/Projects/proj99/Changes/C:/Projects/proj1/notes/Jan_2023.txt"proj99/changes"
    As an example of possible variations, "proj99/changes" could also be entered as "/Proj99/CHANGES/" or "changes\PROJ99" or "C:/projects/proj99/changes/".
    Since this is a somewhat new feature, you're encouraged to think up new uses for it. Any directories you'd like to get at with a single click? Now you can.

    Linking to headings in the same file

    Heading links are only fully implemented in IntraMine's Viewer, and .txt files converted with gloss2html.pl. The Editor does not have links to headings within the same file.
    Again "heading" here means heading in a text file, or a function or class in a source file. Headings in the same file are linked by the Viewer, but not by IntraMine's Editor.
    In a text file:
    To link to a heading in the same text (.txt)file, put it in "double quotes".
    In a source file:
    The links to functions and classes within the same file will happen on their own. No quotes are needed in either source or comments.
    As an example, "Images" will be a link to a section following this one. When you start using IntraMine you'll see same-file links to functions and classes in your source files.
    Web links are full auto, with no need to type double quotes or anything extra. Any text starting with http:// or https:// will become a link. Such as http://google.com.
    Since IntraMine is Perl-based, we have to sneak in a little extra for Perl file viewing. So in Perl files if you "use" a module, you'll get a link to the corresponding file on your system. If you installed the module using cpan (or cpanm etc) you'll also get a link to metacpan.org for the modules. And if it's a module you wrote and are storing locally, there will also be a "pencil" icon link to open the file for editing.

    On-demand linking

    Context-aware autolinking based on partial paths takes a bit of code, and can be slow when doing several thousand lines in one go. IntraMine's Viewer avoids any slowdown by doing on-demand file linking, so that lines of text are processed only when they become visible, and only once. However, the Editor does clear all links and redo the links for visible lines after an editing "spurt" is finished.

    Images

    Image file names are given special treatment:

     • with IntraMine's Viewer, by default you get an "image hover," which is a popup view of the image in your browser window that appears when you pause the mouse cursor over the image file name. Clicking on the image name will produce a view of the image in a new browser tab. In text files there's an "Inline Images" button at the top that lets you switch to full display of the images.

     • in standalone HTML files generated by gloss2html.pl, the choice of image hovers or inlined images is made when you run the program: the default is hovers, add "-i" to the command to have the images inlined. See "gloss2html.pl for standalone Gloss files.html" for details.

    You can put images in any indexed folder, and their file names will be found wherever they are mentioned.
    If you have two different images with the same file name, you can add a bit of the path leading up to the image in order to tell Gloss which image you mean by providing some context. For example, if you wanted the /project51/images/ version of an image called interface.png, in general you could put project51/images/interface.png or just project51/interface.png as the mention. That would pin down which image to show, unless of course you have another /project51/ folder somewhere - in that rare case, you'd need more of the path to tell Gloss which is which. If the mention is in a file that's inside the project51 folder, then just interface.png should do the job. This is the same as for source and text file links.
    As implemented in IntraMine's Viewer, Gloss will also look for images in a specific default directory if no partial path is given and the image isn't found in an indexed location. This is the directory specified by "COMMON_IMAGES_DIR" in IntraMine's data/intramine_config.txt file. The default path is C:\common\images\, and you can change it if you want. If you don't want to put images in a default directory, you certainly don't have to. It's handy though if you use a screen capture app such as Greenshot, where you can set it up to take a screen shot, give it a default name, save the image in a default location, and put the file path on your clipboard.

    Tables

    Simple tables

    Here's a simple Gloss table:
    ​TABLE CodeMirror linkType and class
    linkType Class
    file cmAutoLink
    image cmAutoLinkImg
    web cmAutoLinkNoEdit
    (internal) cmInternalLink
    which displays as
           CodeMirror linkType and class
    linkTypeClass
    filecmAutoLink
    imagecmAutoLinkImg
    webcmAutoLinkNoEdit
    (internal)cmInternalLink
    To make a simple table:

     • put "TABLE" at the beginning of a line, optionally followed by a space and a caption

     • on the next line, put column headers separated by one or more tabs

     • on the following lines put the data, again with columns separated by one or more tabs

     • the table ends when there's a line with no tabs.

    If you want a blank cell, put a space. No toothpicks |, no pavement _, you don't even have to use enough tabs to make it all line up in the original text (but I know that you will).

    Cell span and alignment

    You can have fancier tables if you want, but of course at the price of having to know and type a bit more.
    Put <N> at the beginning of cell contents to indicate how many columns the text should span, where N is an integer. This isn't needed for the rightmost cell, it will take however many columns are remaining to the right.
    Put <L>, <R>, or <C> at the beginning of a cell to indicate left, right, or center alignment. Cell text is aligned left by default, except for text spanning multiple cells, which is center-aligned by default.
    To combine span and alignment, put the alignment and then span in the '<>' at the beginning of the cell's contents, eg <R3> for text aligned right in a three-column span.
    ​TABLE Column span demo
    One Hdr Two Hdr Three Hdr Four Hdr Five Hdr
    d11 <3>d12 3 cells d15
    d21 d22 d23 d24 d25
    d31 d32 <L>d33 3 cells left
    d41 d42 d43 d44 d45
    <R3>d51 3 cells right d54 d55
    Column span demo
    One HdrTwo HdrThree HdrFour HdrFive Hdr
    d11d12 3 cellsd15
    d21d22d23d24d25
    d31d32d33 3 cells left
    d41d42d43d44d45
    d51 3 cells rightd54d55
    ​TABLE Cell alignment
    Temperature Range in Kelvin
    Class Description <R>Low <R>High
    <C>O blue <R>30,000 <R>♾️?
    <C>B blue white <R>10,000 <R>30,000
    <C>A white <R>7,500 <R>10,000
    <C>F yellow white <R>6,000 <R>7,500
    <C>G yellow <R>5,200 <R>6,000
    <C>K light orange <R>3,700 <R>5,200
    <C>M orange red <R>2,400 <R>3,700
    Cell alignment
    Temperature Range in Kelvin
    ClassDescriptionLowHigh
    Oblue30,000♾️?
    Bblue white10,00030,000
    Awhite7,50010,000
    Fyellow white6,0007,500
    Gyellow5,2006,000
    Klight orange3,7005,200
    Morange red2,4003,700

    Gloss vs Markdown tables

    Here's a simple Markdown style table, in plain old HTML:
    <table>
    <th>
    <td>First header</td><td>Second</td><td>Third</td>
    </th>
    <tr>
    <td>Entry one</td><td>Another entry</td><td>Last entry on first row</td>
    </tr>
    <tr>
    <td>Second data row first cell</td><td>row 2 cell 2</td><td>Last entry in table</td>
    </tr>
    </table>
    And here's the equivalent Gloss table:
    ​​TABLE
    First header Second Third
    Entry one Another entry Last entry on first row
    Second data row first cell row 2 cell 2 Last entry in table
    which produces
    First headerSecondThird
    Entry oneAnother entryLast entry on first row
    Second data row first cellrow 2 cell 2Last entry in table
    The HTML version needs 268 characters, and many of them are special. The Gloss table needs 151 characters, of which only five ("TABLE") are at all special.

    Gloss vs MultiMarkdown tables

    Here's a MultiMarkdown table, from
    http://fletcher.github.io/MultiMarkdown-5/tables.html
    | | Grouping ||
    First Header | Second Header | Third Header |

    ◦ | :-----------: | -----------: |

    Content | ✱Long Cell✱ ||
    Content | ✱✱Cell✱✱ | Cell |
    New section | More | Data |
    And more | With an escaped '\|' ||
    [Prototype table]
    ()
    Here's the same table in Gloss, as closely as possible:
    ​TABLE Prototype table
    Grouping
    First Header <C>Second Header <R>Third Header
    Content ✱Long Cell✱
    Content <C>✱✱Cell✱✱ <R>Cell
    New section <C>More <R>Data
    And more With an escaped '|'
    Prototype table
    Grouping
    First HeaderSecond HeaderThird Header
    ContentLong Cell
    ContentCellCell
    New sectionMoreData
    And moreWith an escaped '|'
    MultiMarkdown needs 310 characters, versus 206 for Gloss.
    (Note the divider line just above "New section" is produced by a line in the source containing a single tab, which Gloss collapses vertically into a line.)

    Wider columns

    IntraMine's tables rely on the browser to sort out column widths, but sometimes a column can end up being too narrow, especially if the browser window isn't very wide. To force a column to be wider, add spaces or non-breaking spaces at the end of the heading for the column. Regular spaces seem to do the trick too sometimes, but not always.
    To type a non-breaking space on a Windows box, hold down the ALT key and type 0160. The numbers 0160 must be typed on the numeric keypad for this to work. And NumLock must also be on. My record for remembering that is, I think, about five years.

    Lists

    You can have unordered (bulleted) or ordered (numbered) lists.

    Unordered lists

     • two levels are supported

     • an unordered list item begins flush left with a '-', '+', or '*'.

     • optionally you can put one or more spaces at the beginning of the line.

    ◦ if you put two or more of '-', '+', or '*', eg '--' or '+++', you'll get a second-level entry. To make it prettier in the original text, you can insert spaces at the beginning of the line.

    A top-level or second-level item can continue in following paragraphs. To have the following paragraphs count as part of an item, begin each with one or more tabs or spaces. The leading spaces or tabs will be suppressed in the HTML display.

    This paragraph begins with three spaces in the source, as does the one before.

    ◦ Another second-level item, with excessive spaces.

    To clarify some overlap with horizontal rules: the three or four hyphens '-' for a horizontal rule must be flush left on a line, and followed by nothing else. If there are spaces before the three or four '-' or text afterwards then they count as the start of a second order list item.

    Ordered lists

    An ordered list entry consists of a number and period, or a number period and number, followed by at least one space. There can be spaces or tabs before the first number, but nothing else.
    Ordered lists are auto-numbered, provided the following guidelines are followed:

    1. Two levels, major (2.) and minor (2.4) are supported. Each major entry increments the major number.

    An item can have more than one paragraph, provided each subsequent paragraph starts with one or more spaces or tabs, and there are no intervening blank lines. The leading spaces or tabs will be suppressed in the HTML display.

    2. If the first major entry in a list starts with a number, that number is used as the starting number for the list. Minor levels are always numbered starting at 1.

    2.1 A blank line or regular paragraph that doesn't begin with a space or tab ends the current list and resets numbering.

    2.2 Any continuation paragraph in the same item will have its leading spaces or tabs suppressed.

    Here is a second paragraph for item 2.2.

    And here is a third paragraph, with more leading spaces in the original. Blathering on to make it wrap, blathering on to make it wrap, blathering on to make it wrap.

    3. '#' can be used as a placeholder, but it's not recommended because if you want to refer to a numbered entry you have to know the number. In practice, careful numbering by hand is more useful.

    4. If you use two levels, there should be a major level entry starting off each top-level item, such as the "1." "2." "3." entries in 1., 1.1, 1.2, 2., 2.1, 3., 3.1. Without the major items, the major number will not increment.

    An ordered list example (a bit messed up in the source to show auto-numbering at work):

    3. The first major item, with starting number set to 3.

    3.1 A minor item under 3.

    3.2 Another minor item, incorrectly numbered as 3.3 in the source (corrected to 3.2)

    3.3 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.3)

    3.4 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.4)

    3.5 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.5)

    4. The second major item, correctly numbered in source as 4.

    5. Oops, the source has "6." instead of "5." - this will display as 5.

    5.1 A minor item, 5.1 (source has 6.1)

    5.2 A minor items, 5.2 (source has 6.3)

    5.3 Another minor item. This becomes item 5.3 even though it's "7.1" in the source.

    The source for the above example:

    Emphasis

    Put single asterisks (✱) before and after text to mark it as italic. Put two asterisks (✱✱) both before and after text to mark it as bold. You get <em> for italic and <strong> for bold, which I hope is what you expected.
    For a short code fragment, you can use ✱!✱let x = 10;✱!✱
    This could use a small example. So I'm going to cheat in the original text and use a Unicode heavy asterisk ✱, which Gloss won't convert. The second instance of the example line uses regular asterisks.
    Gloss does ✱italic emphasis✱ and ✱✱bold emphasis✱✱ like this, and code as ✱!✱let x = 10;✱!✱.
    Gloss does italic emphasis and bold emphasis like this, and code as let x = 10;.

    Code blocks

    Please note code blocks are supported only in .txt files. To see a code block rendered in HTML open the .txt file using IntraMine's Viewer, or convert a .txt file to HTML using gloss2html.pl and open the result in your browser.
    To create a code block in a .txt file:

     • put CODE on a line all by itself

     • follow with your lines of code

     • and finish by putting ENDCODE on a line all by itself.

    Here's an example:
    (there's an invisible space before "CODE" to block rendering)
    ​CODE
    sub InlineJavaScriptForFile {
    my ($fileName) = @_;
    my $result = '';
    my $contents = ReadTextFileWide($JS_DIR . $fileName);
    if (defined($contents) && $contents ne '')
    {
    $result = "<script type=\"text/javascript\">\n$contents\n</script>\n";
    }
    else
    {
    die("Error, could not load JavaScript file |$fileName|\n");
    }
    return($result);
    }
    ​ENDCODE
    which is rendered in the HTML version of this file as
    _STARTCB_FL_
    _STARTCB_sub InlineJavaScriptForFile {
    _STARTCB_ my ($fileName) = @_;
    _STARTCB_ my $result = '';
    _STARTCB_ my $contents = ReadTextFileWide($JS_DIR . $fileName);
    _STARTCB_ if (defined($contents) && $contents ne '')
    _STARTCB_ {
    _STARTCB_ $result = "<script type=\"text/javascript\">\n$contents\n</script>\n";
    _STARTCB_ }
    _STARTCB_ else
    _STARTCB_ {
    _STARTCB_ die("Error, could not load JavaScript file |$fileName|\n");
    _STARTCB_ }
    _STARTCB_
    _STARTCB_ return($result);
    _STARTCB_ }
    _STARTCB_FL_
    Text in CODE/ENDCODE is given some minimal syntax styling using lolight (https://github.com/lrsjng/lolight), and a light background color. Anecdotally this is sufficient to fool anyone in HR into thinking they're looking at code.

    Special characters

    Gloss makes certain words and strings stand out a bit. With slight exceptions for "=>", and "NOTE" they are emphasized wherever they occur. Here's the list:
    🎗TODO
    🎗REMINDER
    🎗REMINDERS
    NOTE (if followed by a non-word character such as a space)
    🐝BUG
    🐝BUGS
    ☛ (that's "=>", either at the start of a line or preceded by space)
    💡IDEA!
    ☑FIXED
    ☑DONE
    💩WTF
    🙂 (type a colon ":" followed by a right parenthesis ")", as you already guessed)

    Not wanted on the voyage

    Markdown is aimed at a variety of audiences. Here are some features that documents for intranet use don't really need, for a variety of reasons.
    Gloss doesn't do these
    Item                 Why
    ~~strikethrough~~I have never needed that, have you?
    Definition listGloss provides glossary popups instead. A definition is available wherever a term is used, by stopping the cursor over the term.
    Heading IDGloss links headings automatically: put the heading mentions in double quotes, for example "Overview".
    FootnotesSomething for grander documents.
    Alt text for imagesGloss pops up a view of the image when you put your cursor over the image name. If alt text is needed, you can type it before or after the image name.
    Titles for linksHonestly, too much bother for an intranet document.
    BlockquotePut it in quotes and italicize the author, good enough for most uses.
    Task listTask lists are everywhere. For example, IntraMine's ToDo page🙂
    Gloss does do hashed headings, such as #### This is an h4 heading, but underlining with five or more of = - or ~ just looks better in the original.
    contents.html